Environments
This section describes how ProtectToolkit-C is supplied in different environments, provides development environment guidelines, and lists links to setup and configuration instructions.
Application environment
ProtectToolkit-C can be used in Win64™, Linux, and Java™ environments.
Win64™ environment
ProtectToolkit-C is supplied as a Win64 Dynamic Link Library (cryptoki.dll) built with Microsoft development tools (MSVC). cryptoki2.lib is an import library that should be linked against applications to resolve function calls into cryptoki.dll.
Unix environments
This is supplied as shared libraries. The hardware based ProtectToolkit-C library is stored as the shared library libcthsm.so (libcthsm.a for AIX) and the software-only version as libctsw.so (libctsw.a for AIX). The symbolic link libcryptoki.so (libcryptoki.a for AIX) is setup in the /opt/safenet/protecttoolkit7/ptk/lib folder and should point to the appropriate library. Additionally these libraries must be included in the LD_LIBRARY_PATH (LIBPATH for AIX).
The libcthsm shared object requires the library libethsm.
Java™ environments
A lightweight proprietary Java wrapper for PKCS#11 API, JCPROV, is provided to allow access to the ProtectToolkit-C functionality from Java, without the overhead of the JCA/JCE API. The aim of this API is to be as similar to the PKCS#11 as the Java language allows. This provides a high level of familiarity with the PKCS#11 environment and allows for faster implementation of Java programs.
The Java API is compatible with OpenJDK 7, 8, 9, 10, 11, and 17. The library is implemented in jcprov.jar, under the namespace safenet_tech.jcprov. An accompanying shared library “jcprov” (jcprov.dll in Win32/64 environments, and libjcprov.so in Unix environments (libjcprov.a for AIX) provides the native methods used to access the appropriate PKCS#11 library.
JCPROV Java JNI support (AIX only)
The Java VM on AIX does not support mixed mode JNI libraries, which are shared libraries that provide both 32-bit and 64-bit interfaces. Select the correct JNI library for the Java VM.
-
The /opt/safenet/protecttoolkit7/ptk/lib/libjcprov.a symbolic link must point to a 32-bit version of the library (libjcprov_32.a).
For example: /opt/safenet/protecttoolkit7/ptk/lib/libjcprov_32.a
-
The /opt/safenet/protecttoolkit7/ptk/lib/libjcryptoki.a symbolic link must point a 32-bit version of the library (libjcryptoki_32.a).
For example: /opt/safenet/protecttoolkit7/ptk/lib/libjcryptoki_32.a
-
The /opt/safenet/protecttoolkit7/ptk/lib/libjcprov.a symbolic link must point to a 64-bit version of the library (libjcprov_64.a).
For example: /opt/safenet/protecttoolkit7/ptk/lib/libjcprov_64.a
-
The /opt/safenet/protecttoolkit7/ptk/lib/libjcryptoki.a symbolic link must point a 64-bit version of the library (libjcryptoki_64.a).
For example: /opt/safenet/protecttoolkit7/ptk/lib/libjcryptoki_64.a
Note
When installing the ProtectToolkit-C Runtime package, the above links are automatically created to use the 32-bit versions of the JNI libraries.
Development Environment guidelines
This guide gives a number of application development guidelines that can be of benefit for both novice and advanced developers using ProtectToolkit-C.
An API tutorial is provided in API tutorial: development of a sample application.
Further sample programs, for which source code has been provided, can be compiled and linked against the supplied libraries. Further details about the sample programs are covered in Chapter 5.
The additional libraries ctextra, ctutil, hex2bin and LMlib are static libraries that contain additional PKCS#11 support and helper functions that are not a part of the PKCS#11 standard.
For details on the content of these libraries refer to the following sections:
The library HSMAdmin calls services on the HSM that are not part of the PKCS#11 standard - refer to hsmadmin.h library reference for details.
This development kit can be used to build applications for any variant of the ProtectToolkit-C runtimes.
Note
It is assumed that the Native C/C++ compiler is being used.
Compiling and linking applications on AIX
It is important that new applications link against libraries in the /opt/safenet/protecttoolkit7/ptk/lib directory instead of the libraries in the /opt/safenet/protecttoolkit7/ptk/lib/legacy directory. This can be achieved by using the -L/opt/safenet/protecttoolkit7/ProtectToolkit/lib argument to the compiler or linker. Do not specify the /opt/safenet/protecttoolkit7/ptk/lib/legacy library path, since the legacy shared libraries are deprecated, and support is to be removed in a future release.
You may also want to explicitly specify an embedded library path when linking your own applications and libraries, so that your applications automatically find the required libraries without requiring the LIBPATH environment variable to be set. Do this by using the -blibpath:/usr/lib:/lib:/opt/safenet/protecttoolkit7/ptk/lib option to the linker (ld), or alternatively (if using the compiler to link):
-Wl,-blibpath:/usr/lib:/lib:/opt/safenet/protecttoolkit7/ptk/lib
Compiling and linking 64-bit applications on AIX
To compile 64-bit applications for AIX specify the following compiler and linker flags:
-q64###
MSVC project settings
In order to remove link errors when linking to the additional libraries ctextra and ctutil etc, you need to set the MSVC project settings to Multithreaded under the C/C++ tab of the Code generation category, since this is what the libraries were compiled with.
Also add “_WINDOWS” to the Preprocessor definitions under the C/C++ tab of the General category.
Modes of operation
To switch the ProtectToolkit-C operational mode, you will need to ensure that you are linking to the correct cryptoki.dll. For more information, refer to Changing the Cryptoki provider.
Setup and configuration
For details regarding setup and configuration of ProtectToolkit-C and ProtectServer 3 HSMs, refer to:
